<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Rationale</title>
<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="../index.html" title="Chapter&#160;1.&#160;Fiber">
<link rel="up" href="../index.html" title="Chapter&#160;1.&#160;Fiber">
<link rel="prev" href="custom.html" title="Customization">
<link rel="next" href="acknowledgements.html" title="Acknowledgments">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
<td align="center"><a href="../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="custom.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="acknowledgements.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="fiber.rationale"></a><a class="link" href="rationale.html" title="Rationale">Rationale</a>
</h2></div></div></div>
<h4>
<a name="fiber.rationale.h0"></a>
      <span><a name="fiber.rationale.preprocessor_defines"></a></span><a class="link" href="rationale.html#fiber.rationale.preprocessor_defines">preprocessor
      defines</a>
    </h4>
<div class="table">
<a name="fiber.rationale.preopcessor_defines"></a><p class="title"><b>Table&#160;1.6.&#160;preopcessor defines</b></p>
<div class="table-contents"><table class="table" summary="preopcessor defines">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
            </th>
<th>
            </th>
</tr></thead>
<tbody>
<tr>
<td>
              <p>
                BOOST_FIBERS_NO_ATOMICS
              </p>
            </td>
<td>
              <p>
                no <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">atomic</span><span class="special">&lt;&gt;</span></code>
                used, inter-thread synchronization disabled
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                BOOST_FIBERS_SPINLOCK_STD_MUTEX
              </p>
            </td>
<td>
              <p>
                use <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">mutex</span></code> as spinlock instead of default
                <code class="computeroutput"><span class="identifier">XCHG</span></code>-sinlock with
                backoff
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                BOOST_FIBERS_SPIN_BACKOFF
              </p>
            </td>
<td>
              <p>
                limit determines when to used <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">this_thread</span><span class="special">::</span><span class="identifier">yield</span><span class="special">()</span></code> instead of mnemonic <code class="computeroutput"><span class="identifier">pause</span><span class="special">/</span><span class="identifier">yield</span></code> during busy wait (apllies
                on to <code class="computeroutput"><span class="identifier">XCHG</span></code>-spinlock)
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                BOOST_FIBERS_SINGLE_CORE
              </p>
            </td>
<td>
              <p>
                allways call <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">this_thread</span><span class="special">::</span><span class="identifier">yield</span><span class="special">()</span></code> without backoff during busy wait
                (apllies on to <code class="computeroutput"><span class="identifier">XCHG</span></code>-spinlock)
              </p>
            </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><h4>
<a name="fiber.rationale.h1"></a>
      <span><a name="fiber.rationale.distinction_between_coroutines_and_fibers"></a></span><a class="link" href="rationale.html#fiber.rationale.distinction_between_coroutines_and_fibers">distinction
      between coroutines and fibers</a>
    </h4>
<p>
      The fiber library extends the coroutine library by adding a scheduler and synchronization
      mechanisms.
    </p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
          a coroutine yields
        </li>
<li class="listitem">
          a fiber blocks
        </li>
</ul></div>
<p>
      When a coroutine yields, it passes control directly to its caller (or, in the
      case of symmetric coroutines, a designated other coroutine). When a fiber blocks,
      it implicitly passes control to the fiber scheduler. Coroutines have no scheduler
      because they need no scheduler.<sup>[<a name="fiber.rationale.f0" href="#ftn.fiber.rationale.f0" class="footnote">12</a>]</sup>.
    </p>
<h4>
<a name="fiber.rationale.h2"></a>
      <span><a name="fiber.rationale.what_about_transactional_memory"></a></span><a class="link" href="rationale.html#fiber.rationale.what_about_transactional_memory">what
      about transactional memory</a>
    </h4>
<p>
      GCC supports transactional memory since version 4.7. Unfortunately tests show
      that transactional memory is slower (ca. 4x) than spinlocks using atomics.
      Once transactional memory is improved (supporting hybrid tm), spinlocks will
      be replaced by __transaction_atomic{} statements surrounding the critical sections.
    </p>
<h4>
<a name="fiber.rationale.h3"></a>
      <span><a name="fiber.rationale.synchronization_between_fibers_running_in_different_threads"></a></span><a class="link" href="rationale.html#fiber.rationale.synchronization_between_fibers_running_in_different_threads">synchronization
      between fibers running in different threads</a>
    </h4>
<p>
      Synchronization classes from <a href="http://www.boost.org/doc/libs/release/libs/thread/index.html" target="_top">Boost.Thread</a>
      block the entire thread. In contrast, the synchronization classes from <span class="bold"><strong>Boost.Fiber</strong></span> block only specific fibers, so that the
      scheduler can still keep the thread busy running other fibers in the meantime.
      The synchronization classes from <span class="bold"><strong>Boost.Fiber</strong></span>
      are designed to be thread-safe, i.e. it is possible to synchronize fibers running
      in different threads as well as fibers running in the same thread. (However,
      there is a build option to disable cross-thread fiber synchronization support;
      see <a class="link" href="overview.html#cross_thread_sync">this description</a>.)
    </p>
<a name="spurious_wakeup"></a><h4>
<a name="fiber.rationale.h4"></a>
      <span><a name="fiber.rationale.spurious_wakeup"></a></span><a class="link" href="rationale.html#fiber.rationale.spurious_wakeup">spurious
      wakeup</a>
    </h4>
<p>
      Spurious wakeup can happen when using <a href="http://en.cppreference.com/w/cpp/thread/condition_variable" target="_top"><code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">condition_variable</span></code></a>:
      the condition variable appears to be have been signaled while the awaited condition
      may still be false. Spurious wakeup can happen repeatedly and is caused on
      some multiprocessor systems where making <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">condition_variable</span></code>
      wakeup completely predictable would slow down all <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">condition_variable</span></code>
      operations.<sup>[<a name="fiber.rationale.f1" href="#ftn.fiber.rationale.f1" class="footnote">13</a>]</sup>
    </p>
<p>
      <a class="link" href="synchronization/conditions.html#class_condition_variable"><code class="computeroutput">condition_variable</code></a> is not subject to spurious wakeup.
      Nonetheless it is prudent to test the business-logic condition in a <code class="computeroutput"><span class="identifier">wait</span><span class="special">()</span></code> loop
      &#8212; or, equivalently, use one of the <code class="computeroutput"><span class="identifier">wait</span><span class="special">(</span> <span class="identifier">lock</span><span class="special">,</span>
      <span class="identifier">predicate</span> <span class="special">)</span></code>
      overloads.
    </p>
<p>
      See also <a class="link" href="synchronization/conditions.html#condition_variable_spurious_wakeups">No Spurious Wakeups</a>.
    </p>
<h4>
<a name="fiber.rationale.h5"></a>
      <span><a name="fiber.rationale.migrating_fibers_between_threads"></a></span><a class="link" href="rationale.html#fiber.rationale.migrating_fibers_between_threads">migrating
      fibers between threads</a>
    </h4>
<p>
      Support for migrating fibers between threads has been integrated. The user-defined
      scheduler must call <a class="link" href="scheduling.html#context_detach"><code class="computeroutput">context::detach()</code></a> on a fiber-context on the
      source thread and <a class="link" href="scheduling.html#context_attach"><code class="computeroutput">context::attach()</code></a> on the destination thread,
      passing the fiber-context to migrate. (For more information about custom schedulers,
      see <a class="link" href="custom.html#custom">Customization</a>.) Examples <code class="computeroutput"><span class="identifier">work_sharing</span></code>
      and <code class="computeroutput"><span class="identifier">work_stealing</span></code> in directory
      <code class="computeroutput"><span class="identifier">examples</span></code> might be used as a
      blueprint.
    </p>
<p>
      See also <a class="link" href="migration.html#migration">Migrating fibers between threads</a>.
    </p>
<h4>
<a name="fiber.rationale.h6"></a>
      <span><a name="fiber.rationale.support_for_boost_asio"></a></span><a class="link" href="rationale.html#fiber.rationale.support_for_boost_asio">support
      for Boost.Asio</a>
    </h4>
<p>
      Support for <a href="http://www.boost.org/doc/libs/release/libs/asio/index.html" target="_top">Boost.Asio</a>&#8217;s
      <span class="emphasis"><em>async-result</em></span> is not part of the official API. However,
      to integrate with a <a href="http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/io_service.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">io_service</span></code></a>,
      see <a class="link" href="integration.html#integration">Sharing a Thread with Another Main Loop</a>.
      To interface smoothly with an arbitrary Asio async I/O operation, see <a class="link" href="callbacks/then_there_s____boost_asio__.html#callbacks_asio">Then There&#8217;s <a href="http://www.boost.org/doc/libs/release/libs/asio/index.html" target="_top">Boost.Asio</a></a>.
    </p>
<h4>
<a name="fiber.rationale.h7"></a>
      <span><a name="fiber.rationale.tested_compilers"></a></span><a class="link" href="rationale.html#fiber.rationale.tested_compilers">tested
      compilers</a>
    </h4>
<p>
      The library was tested with GCC-5.1.1, Clang-3.6.0 and MSVC-14.0 in c++11-mode.
    </p>
<h4>
<a name="fiber.rationale.h8"></a>
      <span><a name="fiber.rationale.supported_architectures"></a></span><a class="link" href="rationale.html#fiber.rationale.supported_architectures">supported
      architectures</a>
    </h4>
<p>
      <span class="bold"><strong>Boost.Fiber</strong></span> depends on <a href="http://www.boost.org/doc/libs/release/libs/context/index.html" target="_top">Boost.Context</a>
      - the list of supported architectures can be found <a href="http://www.boost.org/doc/libs/release/libs/context/doc/html/context/architectures.html" target="_top">here</a>.
    </p>
<div class="footnotes">
<br><hr width="100" align="left">
<div class="footnote"><p><sup>[<a name="ftn.fiber.rationale.f0" href="#fiber.rationale.f0" class="para">12</a>] </sup>
        <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4024.pdf" target="_top">'N4024:
        Distinguishing coroutines and fibers'</a>
      </p></div>
<div class="footnote"><p><sup>[<a name="ftn.fiber.rationale.f1" href="#fiber.rationale.f1" class="para">13</a>] </sup>
        David R. Butenhof <span class="quote">&#8220;<span class="quote">Programming with POSIX Threads</span>&#8221;</span>
      </p></div>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2013 Oliver Kowalke<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="custom.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="acknowledgements.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
